dspack v0.3: governance blocks (intents, rules, examples) + surface schema v0.1#9
Conversation
…rface schema v0.1 dspack v0.3 makes a subset of a design system's institutional knowledge machine-checkable. Strictly additive over v0.2: a valid v0.2 document with "dspack": "0.3" validates against the v0.3 schema. - schema/dspack.v0.3.schema.json: v0.2 + three optional top-level blocks. Rules are typed structured predicates (component-choice, required-composition, forbidden-composition) — no expression language; unknown rule types are schema-invalid per version and must fail loudly in linters. Severity is RFC 2119 (must|should); tools map must→error, should→warn. - schema/dspack.surface.v0_1.schema.json: the dspack surface — a protocol-neutral component tree in contract vocabulary, the evaluation target for rules (gates S1/S2/S3) and the payload of examples[].surface. An intermediate representation: never rendered, never transported, always compiled. - spec/dspack-v0.3.md: delta spec with normative per-type evaluation semantics, the severity mapping, gate definitions, the three-layer formulation, and the deliberate expressiveness ceiling. - spec/migration-v0.2-to-v0.3.md: guarantees + worked anti-pattern→rule conversion. - examples/shadcn-ui.dspack.json: upgraded to v0.3 with the destructive-action intent, three worked rules shadowing existing anti-patterns/constraints, and a compilable delete-account example. - scripts/validate.mjs + fixtures/negative/ + CI: schemas compile; examples validate (incl. S1/S2 over example surfaces, cross-reference consistency, and the stripped-document back-compat guarantee); ten negative fixtures must each be rejected. Verify: npm ci && npm run validate && npm run validate -- --fixtures negative Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Introduces dspack v0.3 as an additive delta over v0.2 by defining machine-checkable governance blocks (intents, rules, examples) and a companion “dspack surface” schema used as the evaluation target for governance and as the embedded format for examples[].surface.
Changes:
- Add v0.3 spec + migration guide, and update READMEs to point to the new draft.
- Add new JSON Schemas:
dspack.v0.3(contract) anddspack.surface.v0_1(surface IR). - Add a Node/Ajv validation harness with negative fixtures and CI workflow gating.
Reviewed changes
Copilot reviewed 21 out of 22 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| spec/README.md | Updates spec index to include v0.3 + migration doc and clarifies draft status. |
| spec/migration-v0.2-to-v0.3.md | Adds migration guidance and a worked anti-pattern → rule example. |
| spec/dspack-v0.3.md | Adds the v0.3 delta spec defining intents/rules/examples, surface format, and S1/S2/S3 gates. |
| scripts/validate.mjs | Adds validation harness for schema compilation, examples validation, back-compat, and governance consistency checks. |
| schema/README.md | Updates schema index and documents the new validation harness usage. |
| schema/dspack.v0.3.schema.json | Adds v0.3 JSON Schema including governance blocks and typed rule union. |
| schema/dspack.surface.v0_1.schema.json | Adds generic surface schema (S1) for protocol-neutral component trees. |
| README.md | Updates repository status and milestone list to include v0.3 draft and references. |
| package.json | Adds Node-based validation script and Ajv devDependencies. |
| package-lock.json | Locks Ajv + ajv-formats dependencies for validation harness. |
| fixtures/negative/rule-unregistered-intent.dspack.json | Negative fixture: rule applies to unregistered intent. |
| fixtures/negative/rule-unknown-type.dspack.json | Negative fixture: unknown rule type rejected by schema. |
| fixtures/negative/rule-unknown-example-ref.dspack.json | Negative fixture: rule references missing example. |
| fixtures/negative/rule-unknown-component-ref.dspack.json | Negative fixture: rule references missing component. |
| fixtures/negative/rule-missing-rationale.dspack.json | Negative fixture: rule missing required rationale. |
| fixtures/negative/rule-component-choice-empty.dspack.json | Negative fixture: component-choice rule missing require/forbid arms. |
| fixtures/negative/example-surface-out-of-vocabulary.dspack.json | Negative fixture: example surface uses component not in contract vocabulary (S2). |
| fixtures/negative/example-surface-invalid.dspack.json | Negative fixture: surface fails generic surface schema (S1). |
| fixtures/negative/example-surface-bad-enum.dspack.json | Negative fixture: invalid enum prop value in surface (S2). |
| fixtures/negative/example-missing-intent.dspack.json | Negative fixture: example entry missing required intent. |
| examples/shadcn-ui.dspack.json | Upgrades example contract to v0.3 with intents/rules/examples and an embedded surface example. |
| .github/workflows/validate.yml | Adds CI workflow to run positive and negative validation gates. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…interactive-descendants Design grounds, independent of any demo: ADR-7's repair template is designed to carry a linked example as a corrected reference; the other two rules link one; a rule whose repair feedback cannot include its corrected reference is a contract gap regardless of any demo. Deliberately NOT a new example — the existing one is already in the destructive-action few-shot, so this edit changes repair feedback only (generation context is byte-identical), making the rerun a clean A/B on that single variable. A new example would enter generation context and could suppress first-attempt violations — the line between fixing the contract and rigging the demo. Observed consequence (recorded at exactly this strength, evidence in dspack-gen docs/evidence/2026-07-02-flagship-candidates/): across 11 pipeline runs, rules with a linked example repaired whenever they fired; the unlinked rule never repaired. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Re-review flag (one-line diff): the follow-up commit links the existing |
… sub-component ids Review fixes (Copilot on #9): - Closed governance objects (intentEntry, exampleEntry, appliesTo, and the nested rule requirement/constraint objects) now carry patternProperties ^x-, so x-prefixed extension keys validate per the global v0.2 extensibility rule while non-x unknown keys stay rejected. Spec delta states the compliance explicitly. - buildVocabulary() surfaces duplicate sub-component ids and checkGovernance() rejects them before any id-dependent check — S2 and rule resolution must never depend on object iteration order. Spec delta makes document-wide sub-component id uniqueness normative for contracts using governance blocks; new negative fixture covers it (11 total). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e non-x rejection - checkGovernance() returns early for v0.3 documents that use none of intents/rules/examples — the duplicate-sub-id rule is scoped exactly as spec §5 states it, preserving the strictly-additive guarantee for pure v0.2-shaped documents. - fixtures/negative/intent-non-x-unknown-key.dspack.json: holds the other direction of the extensibility fix in CI — x-owner passes, unknownField is rejected (12 negative fixtures total). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
What this is
PR-1 of Milestone 1 (governed generation vertical slice). dspack v0.3 adds the machine-checkable governance blocks —
intents,rules,examples— plus the companion dspack surface schema (v0.1), the protocol-neutral component tree that rules are evaluated against.Strictly additive over v0.2: a valid v0.2 document with
"dspack": "0.3"validates against the v0.3 schema (checked on every validate run via the stripped-document guarantee).Contents
schema/dspack.v0.3.schema.json— textual extension of the v0.2 schema (everything inherited is structurally identical; verified by the generator's deep diff). Three rule types as a discriminated union:component-choice,required-composition,forbidden-composition. No expression language. Unknown rule types are schema-invalid; linters must fail loudly (exit 4), never skip.schema/dspack.surface.v0_1.schema.json— the surface format: nested component tree in contract vocabulary + declaredintent. An intermediate representation: never rendered, never transported, always compiled.spec/dspack-v0.3.md— delta spec: normative per-type evaluation semantics, severity mapping (contractmust|should→ toolerror|warn, findings carry both), gate definitions (S1 generic schema / S2 contract vocabulary / S3 governance), the three-layer formulation, and the deliberate expressiveness ceiling (§9: ordering, category-based rules, cardinality, tokens/layout — named v0.4 candidates).spec/migration-v0.2-to-v0.3.md— guarantees + a workeddialog-for-destructive-actionsanti-pattern →rule.destructive-requires-alertdialogconversion.examples/shadcn-ui.dspack.json— upgraded to v0.3:destructive-actionintent, three worked rules (one per type) shadowing governance already present as prose, and the compilableex.delete-account-confirmationsurface. Note:rule.button-no-interactive-descendantslists["button", "input"]only — the contract defines neitherselectnortextarea, and rule references must resolve in the contract vocabulary; the fuller list applies to contracts that define those ids (per-review note, ADR-D1 records the category-based v0.4 candidate).scripts/validate.mjs+fixtures/negative/+ CI — the repo's first machine gate: schema-compile, example validation incl. S1/S2 overexamples[].surface, cross-reference consistency, back-compat check; ten negative fixtures spanning schema-, consistency-, S1-, and S2-level rejections, each of which must fail.Acceptance (machine-verifiable)
Both run in CI (
.github/workflows/validate.yml).Hand-review focus
The two schemas and the spec delta (
spec/dspack-v0.3.md§5 evaluation semantics in particular) — these are the milestone's expensive-to-change surfaces. Everything else is gate-verified.ADRs: 1 (typed rules), 2 (canonical surface), 3 (examples), 6 (intents), 11 (severity).
🤖 Generated with Claude Code